chore: Add module examples to User Management Guide and apply consistency in docs #4048

marcabreracast · 2026-01-09T09:30:17Z

Description

This PR consolidates and adds module examples across all migration paths in the User Management migration guide. It is a follow-up to PR #4045, using the Org Invitation → Cloud User Org Assignment migration as the reference pattern for consistency.

Module Examples Added

The following migration guides now include module_maintainer/ and module_user/ examples (v1 → v2 → v3):

Migration Guide	Resource Changes
Org Invitation to Cloud User Org Assignment	`mongodbatlas_org_invitation` → `mongodbatlas_cloud_user_org_assignment`
Project Teams → Team Project Assignment	`mongodbatlas_project.teams` → `mongodbatlas_team_project_assignment`
Project Invitation to Cloud User Project Assignment	`mongodbatlas_project_invitation` → `mongodbatlas_cloud_user_project_assignment`
Atlas User/Users Data Sources	`data.mongodbatlas_atlas_user` → `data.mongodbatlas_cloud_user_org_assignment` `data.mongodbatlas_atlas_users` → `mongodbatlas_organization.users` / `mongodbatlas_project.users` / `mongodbatlas_team.users`

Documentation Improvements

Team Usernames to Cloud User Team Assignment: Simplified the Module considerations section to adapt to template use in previous PR for guidance.

Example Directory RestructuringMigration examples have been reorganized into the following structure:

basic/ - Direct resource usage examples with consolidated README
module_maintainer/ - Module developer migration examples
module_user/ - Module consumer migration examples
README.md - Overview with links to all subdirectories

Basic Example README Consolidation

The following basic/ directories had their version-specific READMEs consolidated into a single parent README for better maintainability:

Example	Change
`migrate_atlas_user_and_atlas_users/basic/`	Consolidated `v2/README.md` and `v3/README.md` into `basic/README.md`
`migrate_project_invitation_to_cloud_user_project_assignment/basic/`	Consolidated `v2/README.md` and `v3/README.md` into `basic/README.md`

Each consolidated README now documents all migration phases (v1 → v2 → v3) with key attribute changes, usage steps, and expected behavior in a single location.
Link to any related issue(s): CLOUDP-344329

Type of change:

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR. A migration guide must be created or updated if the new feature will go in a major version.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR. A migration guide must be created or updated.
This change requires a documentation update
Documentation fix/enhancement

Required Checklist:

I have signed the MongoDB CLA
I have read the contributing guides
I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if appropriate)
I have run make fmt and formatted my code
If changes include deprecations or removals I have added appropriate changelog entries.
If changes include removal or addition of 3rd party GitHub actions, I updated our internal document. Reach out to the APIx Integration slack channel to get access to the internal document.

Further comments

… favor of links to examples

…er readability

…ability

github-actions · 2026-01-09T16:23:22Z

APIx bot: a message has been sent to Docs Slack channel

Copilot

Pull request overview

This PR consolidates migration documentation and adds comprehensive module examples across all User Management migration paths, following the pattern established in PR #4045.

Changes:

Adds module_maintainer/ and module_user/ migration examples (v1→v2→v3) for four migration guides
Restructures example directories with basic/, module_maintainer/, and module_user/ subdirectories
Consolidates version-specific READMEs in basic examples into single parent READMEs for better maintainability

Reviewed changes

Copilot reviewed 78 out of 115 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
examples/migrate_team_project_assignment/v2/README.md	Removed standalone README (content moved to basic/README.md)
examples/migrate_team_project_assignment/module_user/*	Added module consumer migration examples (v1-v3)
examples/migrate_team_project_assignment/module_maintainer/*	Added module developer migration examples (v1-v3)
examples/migrate_team_project_assignment/basic/*	Updated to consolidate README and adjust main.tf
examples/migrate_team_project_assignment/README.md	Updated to reference restructured subdirectories
examples/migrate_project_invitation_to_cloud_user_project_assignment/v2/README.md	Removed standalone README (content moved to basic/README.md)
examples/migrate_project_invitation_to_cloud_user_project_assignment/v3/README.md	Removed standalone README (content moved to basic/README.md)
examples/migrate_project_invitation_to_cloud_user_project_assignment/module_user/*	Added module consumer migration examples (v1-v3)
examples/migrate_project_invitation_to_cloud_user_project_assignment/module_maintainer/*	Added module developer migration examples (v1-v3)
examples/migrate_project_invitation_to_cloud_user_project_assignment/basic/README.md	Consolidated version-specific READMEs into single parent README
examples/migrate_project_invitation_to_cloud_user_project_assignment/README.md	Updated to reference restructured subdirectories
examples/migrate_atlas_user_and_atlas_users/v2/README.md	Removed standalone README (content moved to basic/README.md)
examples/migrate_atlas_user_and_atlas_users/v3/README.md	Removed standalone README (content moved to basic/README.md)
examples/migrate_atlas_user_and_atlas_users/module_user/*	Added module consumer migration examples (v1-v3)
examples/migrate_atlas_user_and_atlas_users/module_maintainer/*	Added module developer migration examples (v1-v3)
examples/migrate_atlas_user_and_atlas_users/basic/README.md	Consolidated version-specific READMEs into single parent README
examples/migrate_atlas_user_and_atlas_users/README.md	Updated to reference restructured subdirectories
docs/guides/atlas-user-management.md	Updated to reference new module examples and simplify documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

erabil-mdb

LGTM! + a few super small suggestions

erabil-mdb · 2026-01-09T17:01:45Z

examples/migrate_atlas_user_and_atlas_users/basic/README.md

+## Usage
+
+1. Start with v1 to understand the original setup
+2. Apply v2 to validate new data sources return expected data


Suggested change

2. Apply v2 to validate new data sources return expected data

2. Apply v2 to validate that new data sources return expected data

erabil-mdb · 2026-01-09T17:03:11Z

examples/migrate_atlas_user_and_atlas_users/module_maintainer/README.md

@@ -0,0 +1,27 @@
+# Module Maintainer Migration Example
+
+This example demonstrates how module maintainers should migrate from `mongodbatlas_atlas_user` data source to `mongodbatlas_cloud_user_org_assignment`.


Suggested change

This example demonstrates how module maintainers should migrate from `mongodbatlas_atlas_user` data source to `mongodbatlas_cloud_user_org_assignment`.

This example demonstrates how module maintainers should migrate from the `mongodbatlas_atlas_user` data source to `mongodbatlas_cloud_user_org_assignment`.

erabil-mdb · 2026-01-09T17:08:31Z

examples/migrate_atlas_user_and_atlas_users/module_maintainer/README.md

+## v1: Initial State
+
+Module using the deprecated `mongodbatlas_atlas_user` data source:
+- Complex role filtering with for expressions


Suggested change

- Complex role filtering with for expressions

- Complex role filtering with `for` expressions

marcosuma

LGTM - one minor comment on the urls for the examples on github (usage of master vs the fixed tag)

marcosuma · 2026-01-12T07:49:32Z

docs/guides/atlas-user-management.md

+  - Replace the deprecated `usernames` attribute with `mongodbatlas_cloud_user_team_assignment` resources inside the module.
+  - Terraform doesn't allow import blocks in modules ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)). Document the import ID format for users: `org_id/team_id/user_id` (or `org_id/team_id/username`).
  - Publish a new module version.
+  - See [module_maintainer example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_user_team_assignment/module_maintainer) for complete implementation.


similar to the ask in the other PR, you're using master instead of a version tag (like in the code you removed just below here). Is this intentional?

It is intentional yes. I synced with Espen about this topic and left a follow-up comment in the other PR clarifying, but in summary, it's safe to leave master, as when the release happens this script that we have replaces all master tags with the fixed release version.

EspenAlbert

I checked the team_project_assignment. And I have the feeling the existing code blocks could be replaced with a link to the basic example.
Also, note how the basic example uses a hardcoded this for the project_name, I don't think that is intentional?

EspenAlbert

Good job on adding all these, but IMO we now have duplicate basic examples and the code snippets shown in atlas-user-management.md
I would refactor to remove the code snippets from the management guide and instead link to the basic examples.
For the Module considerations and Notes/FAQ I also have the feeling that this could stay in the examples/*/README.md files OR stay in the guide and we link from the README's.

marcabreracast · 2026-01-12T10:57:46Z

As we have now duplicate basic examples and code snippets for the migration guide, it's worth reconsidering if we want to keep duplication in the docs. Bringing this point to our tech sync to get team alignment and if needed, a follow-up PR will be created.
CC: @EspenAlbert

…ency in docs (#4048) * Bundle basic resource migration into basic directory * Maintain previous structrue for main file * Add module_user example * Add module_maintainer example * Add example links to migration guide docs * Minor fixes * Bundle example into basic directory * Add module_maintainer example * Add module_user example * Add links to examples on Migration Guide * Add main README and refine docs * Rebundle Atlas user basic example and add example modules * Remove extra verbose module example for cloud user team assignment in favor of links to examples * bundle README files from migration example into a single one for better readability * Rebundle project invitation READMEs into singular one for better readability * Address PR comments * Replace this hardcoded value with project_name variable

marcabreracast added 10 commits January 9, 2026 09:51

Bundle basic resource migration into basic directory

87621df

Maintain previous structrue for main file

e98419b

Add module_user example

2ccd4a5

Add module_maintainer example

b6a7111

Add example links to migration guide docs

120a6e3

Minor fixes

f3ea1c0

Bundle example into basic directory

bef0794

Add module_maintainer example

88624ab

Add module_user example

0d8fc06

Add links to examples on Migration Guide

a4932fc

marcabreracast force-pushed the CLOUDP-344329_Add_Remaining_Module_Examples branch from 02f70c4 to a4932fc Compare January 9, 2026 11:50

marcabreracast added 5 commits January 9, 2026 13:24

Add main README and refine docs

5d15c60

Rebundle Atlas user basic example and add example modules

e14e3f4

Remove extra verbose module example for cloud user team assignment in…

8de3a5f

… favor of links to examples

bundle README files from migration example into a single one for bett…

852b248

…er readability

Rebundle project invitation READMEs into singular one for better read…

05dac42

…ability

marcabreracast marked this pull request as ready for review January 9, 2026 16:23

marcabreracast requested review from a team as code owners January 9, 2026 16:23

Copilot AI review requested due to automatic review settings January 9, 2026 16:23

Copilot AI reviewed Jan 9, 2026

View reviewed changes

erabil-mdb approved these changes Jan 9, 2026

View reviewed changes

marcosuma approved these changes Jan 12, 2026

View reviewed changes

Address PR comments

e8f4ebc

EspenAlbert reviewed Jan 12, 2026

View reviewed changes

Replace this hardcoded value with project_name variable

30ae758

marcabreracast merged commit 49c5856 into master Jan 12, 2026
46 checks passed

marcabreracast deleted the CLOUDP-344329_Add_Remaining_Module_Examples branch January 12, 2026 11:09

	2. Apply v2 to validate new data sources return expected data
	2. Apply v2 to validate that new data sources return expected data

		@@ -0,0 +1,27 @@
		# Module Maintainer Migration Example

		This example demonstrates how module maintainers should migrate from `mongodbatlas_atlas_user` data source to `mongodbatlas_cloud_user_org_assignment`.

	- Complex role filtering with for expressions
	- Complex role filtering with `for` expressions

chore: Add module examples to User Management Guide and apply consistency in docs #4048

chore: Add module examples to User Management Guide and apply consistency in docs #4048

Uh oh!

Conversation

marcabreracast commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Module Examples Added

Documentation Improvements

Example Directory RestructuringMigration examples have been reorganized into the following structure:

Basic Example README Consolidation

Type of change:

Required Checklist:

Further comments

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

erabil-mdb left a comment

Choose a reason for hiding this comment

Uh oh!

erabil-mdb Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

erabil-mdb Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

erabil-mdb Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

marcosuma left a comment

Choose a reason for hiding this comment

Uh oh!

marcosuma Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

marcabreracast Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

EspenAlbert left a comment

Choose a reason for hiding this comment

Uh oh!

EspenAlbert left a comment

Choose a reason for hiding this comment

Uh oh!

marcabreracast commented Jan 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

marcabreracast commented Jan 9, 2026 •

edited

Loading